# Installbox

The *Installbox* setup allows you to automatically install Linux clients on large scale.

## Pre-Requirements

 - A laptop with wireless LAN and gigabit ethernet port
 - A gigabit switch (optional)
 - Network cable(s) to connect the client(s)
 - Wireless internet access where you are NOT using the IPv4 network address range 192.168.20.0/24

# Installbox Setup

 - Create a customized ISO image as described [here](./README_ISO.md).
 - Either burn the image to a CD or write it to a USB key using dd if=debian-installbox-amd64.iso of=/dev/sdb
   (replace sdb with the device node of your USB key, if necessary).
 - Boot the laptop using the CD or the USB key. 
 - Please do not connect the ethernet cable yet.
 - Select the **Install** option during boot.
 - During network setup please select the wireless interface. There should be two interfaces listed:
   eth0 (which is ethernet, don't select this one!) and e.g. wlan0.

    **Note**: If you do not see those two interfaces here, please abort the installation as your device is not supported in that case.
 - After selecting the wireless interface, the installer will search for wireless networks available. Choose your network please.
   Most modern wireless networks use WPA/PSK for authentication, so if you are unsure, you can probably select this option.
 - Type in your Wireless password in the next step. Please note that it's displayed in clear text.
 - Relax, the rest of the installation should work fully automated.
 - After a while the device reboots.
 - You can now log in to your installbox using the default credentials linuxuser/tux.
 - Connect an ethernet cable from the installbox to the gigabit switch or directly to a laptop (1-to-1) on which you want to install Linux on.
 - If you are using a switch, you should now connect the laptops on which Linux should be installed.
 - Select ethernet boot (PXE) as boot option on the machine(s) which should be used for installation.
   On Lenovo you can press F12 and choose the network interface as boot device.

    **Note**: The setup does not ship a default Clonezilla image. Please follow the Workflow section for initial preparation.
 - A NFS share (/exports) has been created on the Installbox.
   This will be available to all clients on the LAN and should contain the clonezilla images.


## PXE Boot Options

When you boot a client, the boot menu will show the following options:

 - Clonezilla Autorestore x86_64 UEFI
   
    This should be started on a client where you want to apply the default image. No interaction needed, all existing data will be deleted.
    It will restore an image called *linux-x86_64-uefi* which must be available in /exports on the installbox.

 - Preseed x86_64 UEFI Debian Stable

    Prepare a 64bit master installation with UEFI support (no Secure Boot).

 - Clonezilla Autosave x86_64 UEFI

    Create an image of a master installation. It will automatically write a disk image to the installbox at /exports/linux-x86_64-uefi.

      **Note**: This will overwrite an existing image of the same name on the Installbox.

 - Clonezilla Live

    Just the default live image with all options and the NFS share already mounted.

 - Boot and Nuke

    Starts dban and will automatically wipe all data on disk.

**Note**: on all options you can press the tab key in order to change settings manually. To permanently adjust the settings, edit /var/lib/tftpboot/prd/pxelinux.cfg/default on the installbox.


## Workflow

After you have set up the installbox a typical workflow would be the following:

1. Create a master image 

  - Choose another laptop on which you want to create the master image
  - Connect the laptop directly to the installbox or to a port on the gigabit switch, which is connected to the installbox
  - Follow the steps described in the 'Prepare Master Image' section

2. Provision laptops with the newly created master image

 - after the master image has been stored on the installbox, choose the relevant Clonezilla Autorestore option from the PXE menu

Once you have created a master image, there is no need to re-create it other than changes needs to be done to it.
Next time, you can just start provisioning clients using the Autorestore option.

> Hint: if unsure, just create a master image for the x86 architecture. This should work on nearly every machine.

### Prepare Master Image

In order to prepare a master image from scratch, please make sure that your installbox laptop has a working wireless lan internet connection.

### Preseed

On a client that is connected to the gigabit switch or directly to the Installbox, start the PXE boot and select the *Preseed x86_64 UEFI* option.
This will set up a base install of Debian Stable with a user called `linuxuser` and the password `tux`.

After preseeding, boot into the newly installed system and apply your customizations.

If you want to modify the preseed file, e.g. to setup a different user account, just edit /var/lib/tftpboot/debian/stable/preseed-uefi.cfg

> Hint: to change the keyboard layout (which defaults to us), simply run dpkg-reconfigure keyboard-configuration after installation.

### Creating the Image

When the client has been set up according to your needs, reboot to PXE and select the relevant Clonezilla Autosave option that fits the architecture of your master setup.

This will automatically save an image to the Installbox which can afterwards be applied to other clients using the Clonezilla Autorestore function for that architecture.

**Note**: this automated process has been optimized for image installations on systems with at least 40GB HDD/SSD space.
If you are in need of installing in on machines with smaller disks, please shrink the root partition before creating the image.

### Image Requirements

If you do not want to use the images that can be prepared with the installbox setup, please make sure that your images
fulfill the following requirements:

 - images that should be deployed automatically using this setup must have the following partition layout:
   bios_grub (1 MB), efi (~ 250 MB), swap (suggested size 4GB),  root (ext4)
 - after preparation of the master, please shrink the root partition to it's minimal size possible.
   This ensures that the image will be deployable on small drives as well and reduze the image creation and deployment process time.

# Resetting the Installbox

You can reset the changes made to the installbox default settings at any time by running /usr/local/sbin/applypuppet as root.

# Additional Notes

 - There is a script available on the installbox called /usr/local/sbin/pxesync.
 
    It can sync the files needed for PXE boot for the Ubuntu and Debian distributions. As default it syncs Debian 'stable', meaning after a new Debian stable release, 
    all you have to do is to execute the script and kernel and initrd used for preseeding will be updated. If you prefer the 'secure' way, you can change it to the
    release-codename instead.
